<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>feval</title>
<style type="text/css">
	body {background-color: white; color: black; font-family:sans-serif; font-size:medium;}
	a:link {color: #3300ff;}
	a:visited {color: #663399;}
	a:hover {color:#0099ff;}
	a:active {color: #0066cc;}
	a.button {text-decoration:none;}
	
	table.nav  {background-color: #dbddff;}
	table.body {margin-top:2ex; margin-bottom:2ex;}
	table.programlistingindent {margin-left:32px;}
	
	img { margin-bottom:0px; margin-top:0px;}
	tt {margin-left:0.5em; margin-right:0.5em; font-weight:lighter;}
	
	p {margin-top:0ex;}
	p.synopsis {margin-left:32px;}
	p.programlistingindent {margin-left:32px;}
	p.citetitle {margin-left:2em;}
	
	ul ul {list-style-type:square;}
	ul li p {margin-top:0ex; margin-bottom:.5ex; padding:0}
	ol li p {margin-top:0ex; margin-bottom:.5ex; padding:0}
	
	h1.reftitle {color:#a90000;}
	h1.reftitle {font-size:3.7ex; margin-top:0; margin-bottom:0; font-weight:bold}
	h1.title {color:black; font-size:4ex; margin-top:1ex; font-weight:bold}
	h2.title {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:3ex}
	h3.title {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:2.5ex}
	h4.title {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:2ex}
	h2 {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:2.5ex}
	h3 {color:#bd0000; margin-top:1ex; margin-bottom:.9ex; font-weight:bold; font-size:2ex} 
	
	pre.programlisting {margin-left:32px;}
	pre.synopsis {margin-left:32px;}
	
	
	.categorytitle {margin-top:8px; padding-top:0px;}
	.categorylist {background-color: #e1e6f2;}
 	</style>
</head>
<body>
<a name="top_of_page"></a><p style="font-size:1px;"></p>
<h1 class="reftitle">feval</h1>
<h2>Purpose</h2>
<p>Evaluates a given function defined over a union of polyhedra.</p>
<h2>Syntax</h2>
<pre class="synopsis">fval = U.feval(x)</pre>
<pre class="synopsis">fval = U.feval(x, function_name)</pre>
<pre class="synopsis">[fval, feasible, idx, tb_value] = U.feval(x, function_name)</pre>
<pre class="synopsis">[fval, feasible, idx, tb_value] = feval(U, x, function_name)</pre>
<h2>Description</h2>
<p></p>
        Evaluates function for a given value of the point <tt>x</tt> over the union of polyhedra <tt>U</tt> characterized
        by the name <tt>function_name</tt>. If the string <tt>function_name</tt> is omitted, it is assumed that only one 
        function is attached to the union.
        The dimension of the vector <tt>x</tt> must be the same as the dimension of the <tt>PolyUnion</tt>.
        If the point lies outside of the union, the result is <tt>NaN</tt>.
        
    Notes:<br><br>
    
      <ul>
        
         <li> 
            <tt>U</tt> must be a single union. Arrays of unions are not accepted. Use
            <tt>array.forEach(@(e) e.feval(...))</tt> to evaluate arrays of unions.
        </li>
        
         <li>
            
            <tt>function_name</tt> must refer to a single function. If omitted, <tt>U.feval(x)</tt>
            only works if the union has a single function.
        </li>
    
      </ul>
    
    
      <b>Outputs</b>
      <br><br>
    
      <ol>
        
         <li> 
            <tt>x</tt> is not contained in any polyhedron of the union:
        
            <tt>fval</tt> = <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval1.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval1.png"> vector of <tt>NaNs</tt>, where <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval2.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval2.png"> is the range of the function,
            <tt>feasible = false</tt>,
            <tt>idx = [] </tt>,
            <tt>tb_value = []</tt>.
        </li>
        
         <li>
            
            <tt>x</tt> is in a single polyhedron:
            
            <tt>fval</tt> = <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval3.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval3.png"> vector of function values,
            <tt>feasible = true</tt>,
            <tt>idx</tt> = index of the set which contains <tt>x</tt>,
            <tt>tb_value = []</tt>.
        </li>
        
         <li>
            
            <tt>x</tt> is contained in multiple polyhedra (either at the boundary or in
            strict interior if there are overlaps), no tie-breaking (default):
            
            <tt>fval</tt> = <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval4.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval4.png"> matrix of function values (<img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval5.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval5.png"> denotes the number of
            polyhedra which contain <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval6.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval6.png">), each column contains the value of <tt>function_name</tt>
            in the corresponding set,
            <tt>feasible = true</tt>,
            <tt>idx</tt> = <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval7.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval7.png"> vector of indices of polyhedra which contain <tt>x</tt>,
            <tt>tb_value = []</tt>.
        </li>
        
        
         <li> 
            <tt>x</tt> is contained in multiple polyhedra (either at the boundary or in
            strict interior if there are overlaps), tie-breaking enabled (see
            below):
            
            <tt>fval</tt> = <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval8.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval8.png"> vector containing the function value in the polyhedra in
            which value of the tie-breaking function is smallest (if there
            are multiple polyhedra with the same tie-breaking value, the first
            such set is considered),
            <tt>feasible = true</tt>,
            <tt>idx</tt> = index of the polyhedron which contains <tt>x</tt> and, simultaneously, has
            the <b>smallest</b> value of the tie-breaking function,
            <tt>tb_value</tt> = scalar value of the tie-breaking function in a polyhedron indexed
            by <tt>idx</tt>.
        </li>
    
      </ol>
        
    
      <b>Tie-breaking</b>
      <br><br>

 The purpose of tie-breaking is to automatically resolve situations
 where the evaluation point <tt>x</tt> is contained in multiple polyhedra. With
 tie-breaking enabled <tt>PolyUnion/feval()</tt> evaluates the tie-breaking function
 to decide which polyhedron containing <tt>x</tt> should be used for evaluation of
 the original function.
 
 The tie-breaking function can be specified by <tt>U.feval(x, 'tiebreak',
 tb_fun)</tt>, where <tt>tb_fun</tt> can be either a string or a function
 handle. A string value must refer to an another function which exists
 in the union <tt>U</tt>.
 
 A typical case where tie-breaking is useful is evaluation of
 discontinuous MPC feedback laws:
 
 <tt>uopt = U.feval(x, 'primal', 'tiebreak', 'obj')</tt>
 
 Here, if <tt>x</tt> is contained in multiple polyhedra, then the function <tt>primal</tt>
 is only evaluated in the polyhedron which contain <tt>x</tt> and simultaneously has
 the <b>smallest</b> value of the tie-breaking function <tt>obj</tt>.
 
 A special case of tie-breaking is the "first-set" rule where we are
 only interested in evaluating a function in the first polyhedron which
 contains <tt>x</tt> (despite the fact there can be multiple such sets). This
 is achieved by
 
 <tt>fval = U.feval(x, 'function_name', 'tiebreak', @(x) 0)</tt>
 
 Notes:
 <ul>
     
         <li> Tie-breaking functions must be scalar-valued.</li>
     
         <li> No tie-breaking is done by default. </li>
 
      </ul>
 
 
      <b>Evaluation in particular polyhedra</b>
      <br><br>
 
 
      <tt>fval = U.feval(x, 'myfun', 'regions', indices)</tt> evaluates function
 <tt>myfun</tt> over all polyhedra indexed by <tt>indices</tt>. The output <tt>fval</tt> is
 always an <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval9.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval9.png"> matrix, where <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval10.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval10.png"> is the cardinality of <tt>indices</tt>.
 
 Note that once the <tt>regions</tt> option is enabled, <tt>PolyUnion/feval()</tt> will not
 perform point location. Instead, it will evaluate the function in all
 polyhedra indexed by <tt>indices</tt>, regardless of whether they contain <tt>x</tt> or
 not.
 
 The <tt>regions</tt> option allows to quickly evaluate multiple functions as
 follows:
 
 <tt>[first_value, idx] = U.feval(x, 'first_function')</tt>
 
      <tt>second_value = U.feval(x, 'second_function', 'regions', idx)</tt>
 
 In the second call, <tt>PolyUnion/feval</tt> will only evaluate <tt>second_function</tt>
 in polyhedra specified by the <tt>indices</tt> option, hence skipping expensive
 point location.

    
	<h2>Input Arguments</h2>
<table cellspacing="0" class="body" cellpadding="4" border="0" width="100%">
<colgroup>
<col width="31%">
<col width="69%">
</colgroup>
<tbody>
<tr valign="top">
<td><tt>U</tt></td>
<td>
<p></p>Union of polyhedra in the same dimension.<p>
	    		Class: <tt>PolyUnion</tt></p>
</td>
</tr>
<tr valign="top">
<td><tt>x</tt></td>
<td>
<p></p>A point at which the function should be evaluated. The point must be given as a column 
        real vector with the same dimension as the <tt>PolyUnion</tt>.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr>
<tr valign="top">
<td><tt>function_name</tt></td>
<td>
<p></p>Name of the function to evaluate. The string must match one of the stored function names.
            If there is only one function attached, this argument can be omitted.
        <p>
	    		Class: <tt>char</tt></p>
</td>
</tr>
</tbody>
</table>
<h2>Output Arguments</h2>
<table cellspacing="0" class="body" cellpadding="4" border="0" width="100%">
<colgroup>
<col width="31%">
<col width="69%">
</colgroup>
<tbody>
<tr valign="top">
<td><tt>fval</tt></td>
<td>
<p></p>Function value at the point <tt>x</tt> over the <tt>PolyUnion</tt> 
         <tt>U</tt>.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr>
<tr valign="top">
<td><tt>feasible</tt></td>
<td>
<p></p>Logical value indicating if the point <tt>x</tt> is contained in the union or not.<p>
	    		Class: <tt>logical</tt><p>Allowed values:</p><ul>
<li><tt>1</tt></li>
<li><tt>0</tt></li>
</ul></p>
</td>
</tr>
<tr valign="top">
<td><tt>idx</tt></td>
<td>
<p></p>Vector of indices of polyhedra that contain the point <tt>x</tt>.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr>
<tr valign="top">
<td><tt>tb_value</tt></td>
<td>
<p></p>Value of the tie-breaking function if the point belongs to multiple polyhedra.<p>
	    		Class: <tt>double</tt></p>
</td>
</tr>
</tbody>
</table>
<h2>Example(s)</h2>
<h3>Example 
				1</h3> PWA function over polyhedral complex. Define one bounded polyhedron in dimension 3.<pre class="programlisting"> P = ExamplePoly.randVrep('d',3); </pre>
<pre class="programlisting"></pre> Triangulate the polyhedron <pre class="programlisting"> T = P.triangulate; </pre>
<pre class="programlisting"></pre> Add linear function to each polyhedron <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval11.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval11.png"> in the array under the name "a". <pre class="programlisting"> T.addFunction(AffFunction([1 -2 0]),'a'); </pre>
<pre class="programlisting"></pre> For each polyhedron in the array add second function 'b'. <pre class="programlisting"> for i=1:length(T), T(i).addFunction(AffFunction(rand(1,3),rand(1)),'b'); end </pre>
<pre class="programlisting"></pre> Create union out of polyhedra <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval12.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval12.png"> with some properties. <pre class="programlisting"> U = PolyUnion('Set',T,'Convex',true,'Bounded',true,'Overlaps',false); </pre>
<pre class="programlisting"></pre> Evaluate the PWA function "a" for a point inside the polyhedron <img src="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval13.png" alt="../../../../../../fig/mpt/modules/geometry/unions/@PolyUnion/feval13.png">. <pre class="programlisting"> x = P.interiorPoint.x; </pre>
<pre class="programlisting"></pre>
<pre class="programlisting"> y = U.feval(x,'a') </pre>
<pre class="programlisting">
y =

        -0.520345123015406

</pre> Evaluate function a with respect to a tie-breaking function 'b' <pre class="programlisting"> yn = U.feval(x,'a','tiebreak','b') </pre>
<pre class="programlisting">
yn =

        -0.520345123015406

</pre>
<h2>See Also</h2>
<a href="../../sets/@ConvexSet/fplot.html">fplot</a><p></p>
<table class="nav" summary="Navigation aid" border="0" width="100%" cellpadding="0" cellspacing="0"><tr valign="top">
<td align="left" width="20">
<a href="eq.html" class="button">&#9664;</a>  </td>
<td align="left">eq</td>
<td>  </td>
<td align="right">isbounded</td>
<td align="right" width="20"><a href="isbounded.html" class="button">&#9654;</a></td>
</tr></table>
<br><p>©  <b>2010-2013</b>     Martin Herceg: ETH Zurich,    <a href="mailto:herceg@control.ee.ethz.ch">herceg@control.ee.ethz.ch</a></p>
<p>©  <b>2003-2013</b>     Michal Kvasnica: STU Bratislava,    <a href="mailto:michal.kvasnica@stuba.sk">michal.kvasnica@stuba.sk</a></p>
</body>
</html>
